<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/strict.dtd">
<html><head>
<title>vector</title>
</head><body>
<p>[<a href="mxdoc.htm">mainpage</a>]
[<a href="tags.htm">tags</a>]<br>
<h1><a name="vector">module: vector</a></h1><p><b>A 100% typesafe generic vector for C.</b><p>

This module contains macros, types and functions for MX_VECTOR whic is a
a 100% typesafe generic vector object for C.  The underlying type must be
bit-copy-correct which means that a binary copy retains proper functioning
and takes over ownership of any internal buffers.
<p>
The interface of MX_VECTOR is done through macros and generic type-indenpendent
functions perform the vector operations.  In contrast to C++ vector types,
the code size when using MX_VECTOR is constant regardless of how many vector
types are instantiated.
<p>
The correct operation of MX_VECTOR depends on some things that not in the C
standard:<ul>
<li>Size of pointer to void and pointer to other types are the same size,
representation and alignment</li>
<li>Writing data in a element of a union and reading out of a different
element works as expected</li>
</ul>
All of the compilers I have tested give no warnings on the
MX_VECTOR code and seem to function properly.  I have tested 16 and 32 bit
compilers as well as compilers with various byte orders.
<p>
MX_VECTOR objects themselves are bit-copy-correct which means that memory 
containing a MX_VECTOR can be safely realloc'd and MX_VECTOR can be used 
inside another MXVECTOR.
<p>
Here is a simple example for doubles but the same concept applies to all
bit-copy-correct types.
<pre>
size_t i;
MX_VECTOR(double) dvect;

mx_vector(&dvect);
mx_vector_resize(&dvect, 100);

for (i=0; i &lt; mx_vector_size(&dvect); i++)
   dvect.data[i] = i;
   
mx_vector_free(&dvect);
</pre>

NOTE: All of the mx_vector* functions are in fact macros that may evaluate
the arguments (the vector) more than once.  This is especially true for the
vector itself (the first argument) and any pointer arguments.  Efforts
have been made to evaluate other arguments only once.  So modifiying
arguments in the macro like this:
<pre>
mx_vector_resize(&dvect, n++);
</pre>
will work as expected.  However code like this:
<pre>
mx_vector_resize(vectptr++, n);
</pre>
will not work as expected.
 
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p>Part of the <a href="deds.htm">deds</a> library.<ul><li>
<a name="define MX_VECTOR(type)"><code>#define MX_VECTOR(type)</code></a>
<p>
<p><b>A 100% typesafe generic vector for C</b><p>
This macro functions as a type delaration for a vector of user-defined
type.  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define MX_VECTOR_ITERATOR(type)"><code>#define MX_VECTOR_ITERATOR(type)</code></a>
<p>
<p><b>An iterator for a MX_VECTOR</b><p>
This macro functions as a type declaration for an iterator for a
similarly typed MX_VECTOR.  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector(mxvect)"><code>#define mx_vector(mxvect)</code></a>
<p>
<p><b>Construct a MX_VECTOR</b><p>
This macro constructs a MX_VECTOR object.  This must be called first
before any other mx_vector_* functions are called.
<p>MX_VECTOR is correctly initialized with a 0 bit pattern.  So static 
MX_VECTOR are correctly initialized and dont necessarily need a call to the 
constructor.  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_free(mxvect)"><code>#define mx_vector_free(mxvect)</code></a>
<p>
<p><b>Destruct a MX_VECTOR</b><p>
This macro destroys an MX_VECTOR object by releasing any memory
that has been allocated.  It should be the last call to any mx_vector_* 
functions.  Access of the MX_VECTOR object after destruction should not be done.  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_at(mxvect, mxn)"><code>#define mx_vector_at(mxvect, mxn)</code></a>
<p>
<p><b>Return an element from a MX_VECTOR at a specific index</b><p>
This macro returns elements from a MX_VECTOR at a specific index.
It is safer than accessing the underlying pointer because it wont allow
access outside the correct range for the vector.   
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_back(mxvect)"><code>#define mx_vector_back(mxvect)</code></a>
<p>
<p><b>Return the last element from a MX_VECTOR</b><p>
This macro returns the last element from a MX_VECTOR.  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_begin(mxvect)"><code>#define mx_vector_begin(mxvect)</code></a>
<p>
<p><b>Pointer to first element</b><p>
This macro returns a pointer to the first data element in the MX_VECTOR object. 
If the MX_VECTOR contains no data elements then 0 is returned.  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_capacity(mxvect)"><code>#define mx_vector_capacity(mxvect)</code></a>
<p>
<p><b>Capacity</b><p>
This macro returns the capacity of an MX_VECTOR object.  This is the 
number of elements that the vector can contain without reqriring any internal
memory management.  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_clear(mxvect)"><code>#define mx_vector_clear(mxvect)</code></a>
<p>
<p><b>Clear</b><p>
This macro deletes all the objects from a MX_VECTOR  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_empty(mxvect)"><code>#define mx_vector_empty(mxvect)</code></a>
<p>
<p><b>Empty</b><p>
This macro deletes all the objects from a MX_VECTOR  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_end(mxvect)"><code>#define mx_vector_end(mxvect)</code></a>
<p>
<p><b>Pointer one-past last element</b><p>
This macro returns a pointer one-past the last data element in the MX_VECTOR object. 
If the MX_VECTOR contains no data elements then 0 is returned.  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_erase(mxvect, mxiter)"><code>#define mx_vector_erase(mxvect, mxiter)</code></a>
<p>
<p><b>Erase an element</b><p>
This macro removes a data element from an MX_VECTOR object.
If there are data elements at indicies higher than those removed then they
are are moved to lower indicies.   
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_push_back(mxvect, mxdat)"><code>#define mx_vector_push_back(mxvect, mxdat)</code></a>
<p>
<p><b>Push an element onto the back of the MX_VECTOR</b><p>
This macro makes a bitwise copy of a single data element and appends 
the copy onto an existing MX_VECTOR object. The size of the vector is expanded 
to hold the new data elements.  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_size(mxvect)"><code>#define mx_vector_size(mxvect)</code></a>
<p>
<p><b>Number of elements</b><p>
This macro returns the size of an MX_VECTOR object.  This is the number 
of data elements that can be safely accessed.   
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_resize(mxvect, n)"><code>#define mx_vector_resize(mxvect, n)</code></a>
<p>
<p><b>Resize</b><p>
This macro resizes a MX_VECTOR object.  If the MX_VECTOR does not have 
sufficient capacity to hold the new number of elements then new space is 
reserved using mx_vector_reserve().  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_reserve(mxvect, n)"><code>#define mx_vector_reserve(mxvect, n)</code></a>
<p>
<p><b>Set capacity</b><p>
This macro reserves space in a MX_VECTOR object for later copying or
appending of data elements.  If enough space is reserved the insertion or appending
of elements does not require memory management (realloc of internal buffer) and 
will be fast.  If enough space is already reserved this macro does nothing.   
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_extend(mxvect, n)"><code>#define mx_vector_extend(mxvect, n)</code></a>
<p>
<p><b>Increase capacity</b><p>
This macro reserves space for additional data elements in a MX_VECTOR object.
If enough space is reserved then future insertion or appending may not require memory
management (realloc of internal buffer) and will therefore be fast. If enough space
is already reserved this macro does nothing. 
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_contract(mxvect)"><code>#define mx_vector_contract(mxvect)</code></a>
<p>
<p><b>Reduce capacity to minimum</b><p>
This macro reduces the memory used by a MX_VECTOR object to the 
minimum required to safely contain the data elements contained. This function can 
cause memory management (realloc of internal buffer) to occur.  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_append1(mxvect, dat)"><code>#define mx_vector_append1(mxvect, dat)</code></a>
<p>
<p><b>Append 1 element (bitwise copy)</b><p>
This macro makes a bitwise copy of a single data element and appends 
the copy onto an existing MX_VECTOR object. The size of the vector is expanded 
to hold the new data elements.  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_append(mxvect, dat, n)"><code>#define mx_vector_append(mxvect, dat, n)</code></a>
<p>
<p><b>Append a number of elements (bitwise copy)</b><p>
This macro makes a bitwise copy of a number of data elements and appends the copies 
onto an existing MX_VECTOR object.  More than one data element can be appended at once. 
If necessary the size of the vector is expanded to hold the new data elements.  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_insert1(mxvect, dat, ind)"><code>#define mx_vector_insert1(mxvect, dat, ind)</code></a>
<p>
<p><b>Insert 1 element (bitwise copy)</b><p>
This macro makes a bitwise copy of one data element and inserts the
copy into an existing MX_VECTOR object.  If necessary the size of the vector 
is expanded to hold the new data element.  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_insert(mxvect, dat, n, ind)"><code>#define mx_vector_insert(mxvect, dat, n, ind)</code></a>
<p>
<p><b>Insert a number of elements (bitwise copy)</b><p>
This macro makes a bitwise copy of a number of data elements and inserts the
copies into an existing MX_VECTOR object at sepcific indicies.  More than one data 
element can be inserted at once.  If necessary the size of the vector is expanded 
to hold the new data elements.  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="define mx_vector_remove_last(mxvect)"><code>#define mx_vector_remove_last(mxvect)</code></a>
<p>
<p><b>Remove last element</b><p>
This macro removes only the last object from a vector.  The size of the MX_VECTOR 
is reduced by one.  
(<a href="../include/deds/vector.h">../include/deds/vector.h</a>)<p></li>
<li>
<a name="size_t mx__vector_makeroom(MX__VECTOR_DATA* vect, const size_t num, const size_t place, const size_t sizeofdata)"><code>size_t mx__vector_makeroom(MX__VECTOR_DATA* vect, const size_t num, const size_t place, const size_t sizeofdata)</code></a>
<p>
<p>During appending we expand vectors by doubling thier size with a
        minimum of 16 but a different value might be better in some applications.
        Can a reasonable API be made for this?  
(<a href="../include/deds/vector/makeroom.c">../include/deds/vector/makeroom.c</a>)<p></li>
</ul><p>Generated by <a href="http://www.deleveld.dds.nl/mxdoc/index.htm">MXDOC</a> 2.2 on Sun Feb  4 15:16:26 2007


</body></html>
